SOURSOP

A Python package for the analysis of simulations of intrinsically disordered and unfolded proteins.

Overview

SOURSOP is a Python-based simulation analysis package built for the conformational analysis of intrinsically disordered regions (IDRs), unfolded states, and other flexible biopolymers. It is built on top of MDTraj, which handles trajectory I/O and the low-level atomic representation, and adds an analysis layer of polymer-physics-aware observables designed specifically for disordered ensembles.

SOURSOP was originally developed by Jared Lalmansingh in the Pappu lab and Alex Holehouse in the Holehouse Lab at Washington University in St. Louis. Since its original release in 2023, we have substantially expanded and extended the codebase.

Features

• Global dimensions & shape — radius of gyration, hydrodynamic radius, end-to-end distance, asphericity, acylindricity, prolateness, and the full gyration tensor.
• Polymer scaling — internal scaling profiles, the apparent scaling exponent ν (with bootstrap confidence intervals), and local scaling heterogeneity.
• Distances & contacts — inter-residue and inter-atomic distance maps, polymer-scaled distance maps, contact maps, and fraction of native contacts (Q).
• Secondary structure — per-frame DSSP assignments and BBSEG backbone-torsion classification.
• Solvent accessibility — per-residue, regional, and site-level SASA, with a dedicated path for one-bead-per-residue coarse-grained ensembles that uses the force field's own per-residue bead sizes (Mpipi, HPS, KH and friends) rather than atomic van der Waals radii.
• NMR observables — random-coil chemical shifts, ³J(HN, Hα) scalar couplings, NOE distances (ssnmr), and paramagnetic relaxation enhancement (sspre), computed by default with a coarse-grained spin-label cloud model (calibrated against DEER-PREdict) that works on all-atom and coarse-grained trajectories alike.
• Ensemble reweighting — a consistent, deterministic per-frame weights system across the package, with Bayesian Maximum Entropy (ssbme: BME / iBME / BMECustom) and Convex Optimization for Ensemble Reweighting (sscoper: COPER / iCOPER) for reweighting ensembles against experimental data.
• HDX protection factors — Best–Vendruscolo ln(P) predictions (sshdx).
• Sampling diagnostics — convergence assessment of disordered-protein ensembles via PENGUIN (sssampling).
• Multiple resolutions — all-atom and one-bead-per-residue coarse-grained trajectories, with automatic detection.

Installation

SOURSOP can be installed from PyPI with either pip or uv:

pip install soursop
# or
uv pip install soursop

To install the latest development version directly from GitHub:

pip install "git+https://github.com/holehouse-lab/soursop.git"

Verify the installation with:

python -c "import soursop; print(soursop.__version__)"

Full installation instructions (conda, editable/source installs, and running the tests) are in the documentation.

Quickstart

import numpy as np
from soursop.sstrajectory import SSTrajectory

# read in a trajectory (trajectory file + topology file)
traj = SSTrajectory('traj.xtc', 'start.pdb')

# extract the first protein chain (an SSProtein object)
protein = traj.proteinTrajectoryList[0]

# ensemble-average radius of gyration and end-to-end distance
rg  = np.mean(protein.get_radius_of_gyration())
ree = np.mean(protein.get_end_to_end_distance())

# ensemble-average inter-residue distance map
dmap = protein.get_distance_map()

print(f"Rg  = {rg:.2f} Å")
print(f"Ree = {ree:.2f} Å")

See the worked examples in the documentation for end-to-end analyses.

Documentation

Full documentation, including installation, tutorials, worked examples, and the complete API reference, is hosted at soursop.readthedocs.io.

Versioning and changelog

The current release is the 2.0.x series, a large maintenance, performance, documentation, and feature release relative to the previous 0.2.7 line. It adds a consistent ensemble-reweighting (weights) system across the package, two new modules for deriving frame weights from experimental data (ssbme: BME / iBME / BMECustom, and sscoper: COPER / iCOPER), new experimental forward-model observables (scalar ³J(HN, Hα) couplings and NOE distances in ssnmr, plus HDX protection factors in the new sshdx module) — alongside wide-ranging bug fixes and behaviour-preserving speed-ups. 2.0.2 added a coarse-grained spin-label cloud model to the sspre PRE calculation and made it the default — a breaking change relative to the point-at-CB model of 2.0.1 (pass use_label=False to reproduce older profiles). 2.0.3 makes multi-model PDB files load ~2x faster and fixes a batch of correctness bugs from a package-wide review (a few of which change numerical output — notably get_local_to_global_correlation, coarse-grained/COM-mode strided distance maps, get_clusters, and DSSP fractions at termini). 2.0.4 adds first-class SASA support for one-bead-per-residue coarse-grained models, computed against each model's own bead sizes — a breaking change, in that SASA on a coarse-grained chain now requires the force field to be named (e.g. forcefield='mpipi-gg') rather than silently treating every bead as a carbon atom. The latest 2.0.5 is a correctness and documentation release from a follow-up package-wide review — six bug fixes (one interpreter-crashing, several silently-wrong) with regression tests for each. See the changelog for details.

The full, versioned changelog is in CHANGELOG.md.

Reporting bugs and requesting features

If you find a bug, typo, or error, please raise an issue on GitHub.

If you wish to add a new feature or contribute a plugin, please see the development documentation.

Citing SOURSOP

If you use SOURSOP in your work, please cite:

Lalmansingh, J. M., Keeley, A. T., Ruff, K. M., Pappu, R. V. & Holehouse, A. S. SOURSOP: A Python Package for the Analysis of Simulations of Intrinsically Disordered Proteins. J. Chem. Theory Comput. 19, 5609–5620 (2023). doi:10.1021/acs.jctc.3c00190

• Journal link
• Paper PDF

License

SOURSOP is distributed under the GNU Lesser General Public License v3.0 (LGPLv3). See LICENSE for the full text.

Copyright © 2014–2026 Alex Holehouse and contributors.

Acknowledgements

Project structure based on the Computational Molecular Science Python Cookiecutter version 1.0.